GDR Designer Introduction

Introduction to GDR (General Document Recognition)

The GDR capability enables the document recognition of your application generated files. It enables the automatic recognition, conversion and sending of documents, based on their contents.

Files to be processed are placed in a directory polled by the GDR Pickup Service. The contents of the files found in this directory is analyzed by the GDR Engine, according to the defined GDR templates. These templates are created with the GDR Designer, and enable the GDR Engine to identify documents in files, and find in each type of document the information required for its transmission. Once analyzed, documents are processed by the fax server and sent to their recipients: documents to be sent sent by fax are put in the pending database and treated by the fax server ; documents to be sent by email or printed are put in the delivery database and treated by the corresponding client connector.

In order to have your documents processed by the GDR Engine, the GDR Pickup Service must be started on the fax server. Refer to GDR Pickup Service help in the Faxgate Administrator for details on its settings.


Using GDR Designer - Overview

GDR Designer is a tool that lets you define GDR templates used to identify the documents to be processed and to analyze their contents. This analysis is performed in two steps:

  • First, you need to identify the type of the document to process and to delimit its contents.

  • Then, you need to determine the type of the recipient information (fax number, e-mail address, printer path) and where to find it in the document.

GDR Designer is shipped with two pluggins that let you perform queries to LDAP and ODBC address books.

This section describes you how to create, save and modify your own GDR templates.


Creating a new GDR template

Creating a GDR template

You can create new GDR templates for your document types from Faxgate Administrator. Right-click the GDR Pickup service\GDR Templates folder and select New then GDR Template from the context menu.

A wizard will help you to define your GDR template. This wizard will help you to define your GDR template with the following steps:

  • Setting how to identify the document,

  • Setting the recipient type (fax, email),

  • Setting the recipient information to retrieve in the document,

  • If necessary, setting a request to a phonebook (LDAP or ODBC) to retrieve the needed recipient information.

Note that you need a reference file of the documents for which you are creating the recognition template. This reference file must be as generic as possible and be structured like all the documents of this type.

Note that you need a reference file of the documents for which you create the recognition template.


Wizard: Welcome property sheet

Wizard - Welcome property sheet

This Wizard is automatically displayed when you create a new GDR template (.rlg extension file) for a type of document. It allows you you to:

  • Define data that will enable the fax server to identify documents of this type;

  • Localize useful information in these documents from a reference file. This information will enable the fax server to process the document.

File Name

Enter the path and name of your reference document, or click the [image] button to browse your drives and select it.

Note

GDR Designer recognizes documents in text format.


Wizard: Document Recognition property sheet

Wizard - Document Recognition property sheet

You can choose between two methods to identify the document type:

  • Recognize the document by name: You need to specify the name of the file(s) that contain documents of this type (full name or wildcards).

  • Recognize the document by content: You need to specify a string that is specific to the document and that always appears at a specific location in this document. This string will be used as a marker.

Select one of these options, and click Next.


Wizard: Document Recognition (from name) property sheet

Wizard - Document Recognition (from name) property sheet

Enter the name of the file(s) to which the GDR template will apply. You can use the following wildcards:

* | States for one or more unknown character(s) in the string. Ex: *.bat will list all files ending with ".bat".
? | States for one unknown character in the string. Ex: File??.bat will list all files starting with "File", followed by two characters, and ending with ".bat" (File01.bat, File02.bat, etc.).

For instance:

  • If you want to apply the GDR template to a single documents file only, specify the full name of this file: "Myfile.txt".

  • If you want to apply the GDR template to several documents files of the same type, but whose name varies partly (for instance: Myfile00.txt, Myfile01.txt, Myfile02.txt...), use one of the following notations: "Myfile??.txt" or "Myfile*.txt".

  • If you want to apply the GDR template to all the files that have a given extension (*.cmd, for instance), use the following notation: "*.cmd".

Note

A file may contain one or more documents to recognize.


Wizard: Document Recognition (from contents) property sheet

Wizard - Document Recognition (from contents) property sheet

Enter a character string to recognize and its coordinates in the document, or click the Capture button to select this string in the reference document, and automatically enter its coordinates.

The coordinates are rectangle cooordinates and are given in the following order: top-left and bottom-right (note that to make sense, top value must be lower than bottom value, and left value must be lower than right value).

Note that you will be able to change these settings later, and add new conditions. See Changing the GDR template document settings.

Note

By default, string recognition is not case sensitive.


Wizard: Page and document break property sheet

Wizard - Page and document breaks property sheet

Once the type of a document is recognized, you must indicate in the template:

  • How new pages are recognized in this document: this will allow GDR Engine to determine the number of pages the fax server will have to route to the destination user. This is the page break definition. By default page break is made on a Form Feed.

  • When the document is ending, i.e. when a new document is recognized. This is the document break definition. By default document break is made on a new page.

Page break

Select one of the following options to set page break(s):

  • On a Form Feed. Form Feed (FF) is a special character that causes printers to advance one page forward or to the top of the next page (see ASCII Control Characters). This option will force GDR to insert an hard page break each time the Form Feed character appears in the document.

  • When a number of lines is reached. This option allows you to set a number of lines per page of your document. Enter in the field the number of lines after which GDR will automatically begin a new page.

  • Other. This option allows you to set more avanced settings. See Page break property sheet.

Document break

Select one of the following options to set document break(s):

  • On a page break. This option will cause GDR to interpret a page break as the end of the current document.

  • When a number of lines is reached. This option allows you to set the number of lines of the document. Enter in the field the number of lines after which GDR will consider a new document has started.

  • When a number of pages is reached. This option allows you to set the number of pages of the document. Enter in the field the number of pages after which GDR will consider a new document has started.

  • Other. This option allows you to set more avanced settings. See Document break property sheet.


Wizard: Send mode property sheet

Wizard - Send mode property sheet

You must indicate the send mode for the documents: fax, email or to a printer.

  • Select Fax if you want your documents to be faxed. The FaxNumber predefined variable will be used to contain the fax number value.

  • Select E-mail and the email type if you want your documents to be sent by email. The RecipientAddress and RecipientType predefined variables will be used to contain the email address value and the type of this email address.

  • Select Printer if you want your documents to printed. The Printer predefined variable will be used to contain the printer path.

Note that you can use several modes in the same template: the first send mode will be configured through the template creation wizard, and you will have to add variables to configure the other modes. But each send mode can only be used once.


Wizard: Data Extraction property sheet

Wizard - Data Extraction property sheet

You must indicate how the transmission information (destination user fax number, email address, printer path) can be retrieved in documents of this type. Select one of the following options:

  • The data lies in the document file. For example, you will find a fax number at a specific position in the document.

  • The document file contains an identifier, which will be used to find the data in an ODBC phonebook. For example, you will find an user identifier at a specific position in the document, which will enable you to retrieve the user fax number from an ODBC phonebook.

  • The document file contains an identifier, which will be used to find the data in an LDAP phonebook. For example, you will find an user identifier at a specific position in your document, which will enable you to retrieve the user fax number from a LDAP phonebook.

  • The data have a fixed value. This option allows you to set constants. For example, you will send all documents to the same fax number.


Wizard: Data Extraction property sheet

Wizard - Data Extraction property sheet

Destination name

This field indicates in the GDR template the area variable containing the information used to transmit the message: either the transmission information directly (FaxNumber, RecipientAddress, Printer), or an identifier (DestIdent, RecipientAddressIdent, PrinterIdent). See Predefined variables.

Area coordinates

Enter the coordinates of the area containing the transmission information, or click the Capture... button to select this area in the reference document, and automatically enter its coordinates.

The coordinates are rectangle cooordinates and are given in the following order: row and column of top-left corner, row and column of bottom-right corner (note that to make sense, top value must be lower than bottom value, and left value must be lower than right value).

The value contained in the selected area will be displayed in the Extracted value field.

Click the Advanced... button to set advanced data extraction rules.


Wizard: ODBC Data extraction property sheet

Wizard - ODBC Data extraction property sheet

Select a data source

Select a data source from the drop-down list. If the list is empty, you must define your data source by clicking the New... button.

Note

All data sources you declare are saved in a special file named common.ilg, located in the \GDRRules directory on the fax server. If you replace this file or remove it, then all data sources that were previously declared won't be available anymore from GDR Designer.

Select table in the datasource

Select the table in the data source in which you want to retrieve information. The Table list gives the tables in the selected database.

Select the field matching with the extracted variable

In the Field list, select the field in your data source table whose value must match the extracted variable value. This list gives the fields in the selected data source table.

Select the field containing the output data

In the Field list, select the field in your data source table that contains the data value you want to retrieve from the data source. This list gives the fields in the selected data source table. The retrieved value will be assigned to the output variable.


LDAP Request: General property sheet

LDAP Request - General property sheet

Use the fax server LDAP phonebook

Select this check box to use the fax server LDAP phonebook. In this case, the LDAP connection fields will be automatically completed. Otherwise, uncheck this option and enter the connection parameters for access to your LDAP database.

Connection

Complete the connection parameters enabling you to access to the LDAP database that contains the information you want to retrieve:

  • Enter the name of the LDAP server or its IP address in the Host field.

  • Indicate the port value (default is 389).

  • Enter the user name and password if required to connect to the LDAP database.

Proxy

Advanced. If you use a proxy server, indicate its name or IP address and its port.


Wizard: LDAP Data extraction property sheet

Wizard - LDAP Data extraction property sheet

Select a search path

Enter the DN path of the reference object from which you want to start the search in the Ldap database. Click the [image] to select this path from your database directories.

Variable to test

Select in the Matching Attribute list the LDAP attribute whose value must match the value of the variable to test.

Attribute to extract

Select in the Result Attribute list the attribute that contains the data value you want to retrieve from the database. The retrieved value will be assigned to the result variable.


Wizard: Constant Definition property sheet

Wizard - Constant Definition property sheet

Destination name

Name of the variable that you will set as a constant (see predefined variables).

Value

Enter the constant value for the variable.


Opening a GDR template

Editing/Modifying a GDR template

You can edit and modify GDR templates from Faxgate Administrator. Right-click the GDR template you want to edit/modify in the GDR Pickup service\GDR Templates folder and select Open from its context menu. This will open your template in the GDR Designer application and let you make changes if required.


Saving the GDR template

Saving/renaming a GDR template

To save a template, select Save from the File menu in the GDR Designer application.

Then, you can change the name of the GDR template from Faxgate Administrator: exit GDR Designer, right-click the GDR template in the list view, select Rename from its context menu and type its new name.


Changing the GDR template document settings

To change the current GDR template document settings, select Settings from the Document menu.

You can also double-click the blue rectangle recognition area displayed in your GDR template reference document. Note that this blue area only appears if recognition is made from the contents of you document (refer to Document settings: General property sheet).


Document settings: General property sheet

Type of document - General property sheet

You can change here the file recognition condition you set when running the wizard, and add more conditions if needed.

First, choose the way of recognition you want to use: from the file name or from the contents.

Recognition from the file name

In this case, enter the name of the file. You can use the following wildcards: "*" and "?".

Recognition from the contents

In this case, you can set one or more conditions that will need to be matched.

There must be at least one condition.The first condition in the list is an If condition. Then, the other conditions can be And or Or conditions.

  • To add a new condition, click [image]. It will be added at the end of the list.

  • To delete a condition, select it and click [image].

  • To sort the conditions in the list, select them, and use the [image] and [image] buttons. Note that if you move a condition to the beginning of the list, this condition will become an If condition.

Enter a character string to recognize in the Value field, and its coordinates in the document in the Area fields. Or click the Capture button to select this string in the reference document: the Value and Area fields will be automatically completed.

The coordinates in the Area field are rectangle coordinates and are given in the following order: row and column of top-left corner, row and column of bottom-right corner (note that to make sense, top value must be lower than bottom value, and left value must be lower than right value).

You can select the Operator for the condition:

= | The selected area contents must exactly match the Value field contents.
<> | The selected area contents must be different from the Value field contents.
contains | The selected area contents must contain the Value field contents.
not contains | The selected area contents must not contain the Value field contents.

Select the Case sensitive check box if you want the string recognition to be case sensitive.


Document settings: Page break property sheet

Type of document - Page break property sheet

You can set one or more conditions to indicate when a page break is to be recognized in the document. If several conditions are entered, a page break is identified when one of these conditions is validated.

Number of lines

This option allows you to set a number of lines per page of your document. Indicate the number of lines after which GDR will insert a page break and begin a new page.

String

This option allows you to set a string that will be interpreted by GDR as a page break in your document.

Enter the character string to be detected in the String field (or click the Capture button to select this string in the reference document), or select one of the default codes by clicking the [image] button:

  • Form Feed (^L). Advances one page forward or to the top of the next page. Also known as FF.

  • Line Feed (^J). Moves down one line. Also known as LF.

  • Carriage return (^M). Moves to the beginning of the next line. Also known as CR.

  • Control character (^). Special, non-printing character that, associated to another character, has a specific meaning for some devices (display screens, printers, etc.). The ASCII character set defines 32 control codes (see ASCII control characters).

If this string is detected in your document, a page break will be inserted.

By default, the page break will be inserted on the line following the line where the string was detected. You can change this by selecting one of the options in the Include String drop-down box:

  • String excluded: the page break is inserted before the detected string.

  • String included: the page break is inserted after the detected string.

  • String absorbed: the page break replaces the detected string.

  • Line excluded: the page break is inserted on the line preceeding the detected string line.

  • Line included: the page break is inserted on the line following the detected string line.

  • Line absorbed: the page break replaces the detected string line.

You can also set in the Starting in column field the position on the line from which the string can be detected. So, if you define the string "\line", and set 20 as Starting in column value, then if "\line" is detected at row 19 or before on a line, no page break will be inserted, and if "\line" is detected at row 20 or after on a line, a page break will be inserted.

Click OK to validate your changes.


Document settings: Document break property sheet

Type of document - Document break property sheet

You can set a condition to indicate when a document break is to be recognized in the document.

You can select one of the following options:

  • Number of pages

  • Number of lines

  • When a new document is recognized

  • String

Number of pages

This option allows you to set the number of pages of the document. Enter the number of pages after which GDR will consider a new document has started.

Number of lines

This option allows you to set the number of lines of the document. Enter the number of pages after which GDR will consider that a new document has started.

When a new document is recognized

This option is only available if recognition is made from document contents. It causes a document break to be inserted only when a new document is recognized, i.e. when the recognition from contents condition you set before is validated (refer to Document General Settings property sheet for details).

You can choose to check if this condition is validated either every line or every page.

String

This option allows you to set a string that will be interpreted by GDR as a document break in your document.

Enter the character string to be detected in the String field (or click the Capture button to select this string in the reference document), or select one of the default strings by clicking the [image] button:

  • Form Feed (^L). Advances one page forward or to the top of the next page. Also known as FF.

  • Line Feed (^J). Goes to the next line. Also known as LF.

  • Carriage return (^M). Moves to the beginning of the next line. Also known as CR.

  • Control character (^). Special, non-printing character that, associated to another character, has a specific meaning for some devices (display screens, printers, etc.). The ASCII character set defines 32 control codes (see ASCII control characters).

This string will be interpreted as the end of the current document: a document break will be inserted.

By default, the document break will be inserted on the line following the line where the string was detected. You can change this by selecting one of the following options in the Include String drop-down box:

  • String excluded: the page break is inserted before the detected string.

  • String included: the page break is inserted after the detected string.

  • String absorbed: the page break replaces the detected string.

  • Line excluded: the page break is inserted on the line preceeding the detected string line.

  • Line included: the page break is inserted on the line following the detected string line.

  • Line absorbed: the page break replaces the detected string line.

You can also set in the Starting in column field the position on the line from which the string can be detected. Thus, if you define the string "\line", and set 10 as Starting in column value, then if "\line" is detected at row 9 or before on a line, no document break will be inserted, and if "\line" is detected at row 10 or after on a line, a document break will be inserted.

Click OK to validate your changes.


Document settings: Options property sheet

Type of document - Options property sheet

Tabulations

Enter the text tabulations size (in number of characters).


Changing the current template reference document

When creating a template, you must indicate a reference file, as generic as possible, of the documents for which you create the template. Once your template is created, you can change this reference file if needed.

Open your GDR template in GDR Designer, and select Change reference document&ldots; from the Document menu.


Testing templates - Overview

Once you have created a GDR template, you may need to test that it works properly with your documents, or send a test document to check if this document is properly sent to its recipient.

If you have problems with your GDR templates, consult the troubleshooting section. It shows you how to analyse why your documents processed with the GDR Engine failed, and what you should do.


Testing the GDR template

To test your GDR template, select Test from the Document menu.

This will open the Test dialog box.


Test

This dialog allows you to test GDR templates on your documents.

You can test the current GDR template (the one currently open in GDR Designer) either on the current document (usually the one you choose as reference document) or on another document.

By default, the test is made with the current GDR template on the document used as reference.

The test dialog box will display:

  • The type of the document tested, i.e. the name of the GDR template that will be use to process the document.

  • The number of pages in the document.

  • The contents of all variables declared in the GDR template.

Changing the document used for test

To select another document to test, click the [image] icon. Select the file containing the document to test.

To select back the document used as reference (the one open in GDR Designer), click the [image] icon.

Testing the current GDR template or all templates

To test the selected document with all GDR templates defined in the template directory, press the [image] toggle button.

To test the selected document with only the current GDR template, depress the [image] toggle button.


HowTo Sending a test document

Sending a test document

If you want to send a test document file with GDR from Faxgate Adminitrator, use one of the following methods:

  • Select the document file to be processed by GDR in your Windows Explorer. Drag and drop it to the GDR Pickup service\Files to process folder in Faxgate Adminitrator.

  • Right-click the GDR Pickup service\Files to process folder in Faxgate Adminitrator and select New then Text file. Enter the text of the file to be processed by GDR, name it and click Finish.

Then, you can check under the Queue Manager component to see that the test documents were sent correctly:

  • If a document was to be sent by fax, the fax should appear under \Outgoing\Current\Sent.

  • If a document was to be sent by email or printed, it should appear under \Incoming\Current\Delivered.


HowTo Troubleshooting

Troubleshooting

Analyzing why a document processed with the GDR Engine failed

When the process of a file with the GDR Engine fails, the document(s) not sent will be archived in a \Failed subdirectory of the \GDR Pickup Service\Archived Files directory of the Faxgate Administrator.

This topic tells you how to carry out analysis if your documents continue to fail.

If a document is not sent, it means that the document destination information (fax number, email address or other) has not been retrieved, for one of the two following reasons:

  • The GDR template has not been properly defined (setting up errors, particular cases not taken into consideration, reference document not generic enough).

  • The document has not been processed with the right template.

Proceed as follows:

  1. Open in GDR Designer the template with which your document is to be processed.

  2. Select the Test option from the Document menu. By default, this window displays the result of the test in the GDR template open in the reference document of this template. Check that the variable containing the destination information (fax number, email address) is not empty and contains a consistent value.

    • If not, the template is not correctly defined: you will then need to check all the parameters and modify it so that the recovered destination information is consistent.

    • If it is, move on to the next point.

  3. From the Test window, click on the [image] button and select the file containing the document that failed. Check that the variable containing the destination information (fax number, email address, printer path) is not empty and contains a consistent value.

    • If not, the template is not correctly defined: the reference document is not generic enough or some particular cases are not covered; you must modify the template until the recovered destination information is consistent.

    • If it is, move on to the next point.

  4. From the Test window, click on the button. The test is then run using all the GDR templates defined on the fax server. The name of the template processing each document appears in the Document type column. Check that your document is being processed with the right template (the one open in GDR Designer).

    • If not, you must check the template used instead and redefine correctly how the document is recognized (for instance, if in a template you recognize a document by the file name containing it " File00.txt " and in another template, you recognize the document by the " F*.txt ", file name, there will necessarily be some ambiguity).

  5. Once you have identified the origin of the problem and you have corrected it, you can submitted the failed document(s) again. To do this, select the failed document file from the Failed sub-directory of the \GDR Pickup Service\Archived Files directory, and drag and drop it into the \GDR Pickup Service\Files to process directory. This file only contains the origin file documents that have failed: accordingly, those that had been submitted successfully will not be sent again.


Managing variables and requests Overview

Managing extracted data (variables) - Overview

When you create a GDR template with the wizard, one or more variables are created to contain the recipient information. Depending on the extraction mode, a request to a phonebook may also be created.

Once your template is created, you can add new variables if needed: for example, to set cover pages fields, notification options or send parameters.

All template variables appear in the Extracted data list. Variables can be associated to an extraction area, a phonebook request, a data validation rule or have a constant value.

You can check and/or change variables settings by displaying variables properties.

If you need to remove variables, you can check first where these variables are used (extraction area, phonebook request or data validation rule) by finding references to variables.


Adding variables

To set new variables in your GDR template, click the [image] button.

The variable creation wizard is displayed. Follow the instructions to create the new variable.


Wizard: Operation property sheet

Wizard - Operation property sheet

The variable creation wizard helps you to create new variables in your template.

Select the type of variable you need to create, and click Next:

  • Recipient address variable (fax number, email address, printer path),

  • Cover page variable,

  • Other predifined variable,

  • Custom variable.


Wizard: Cover page property sheet

Wizard - Cover page property sheet

Select the predefined variable corresponding to the cover page field you want to use.

By default, the cover page set on the fax server will be sent with your documents. If you want to set another cover page to be used, you must configure the CoverTemplate predefined variable. If you want to prevent the use of the fax server default cover page, you must assign a blank value to the CoverTemplate predefined variable.


Wizard: Predefined variables property sheet

Wizard - Predefined variables property sheet

Select the predefined variable corresponding to the variable/option you want to configure.


Viewing the list of variables

Viewing the list of extracted data (variables)

To display the list of variables defined in your GDR template, select Extracted data... from the Document menu.

This will open the Extracted data dialog box.


Variables

Extracted data

This dialog box lists all the variables defined in the GDR template.

List

To change the action that sets the value of a variable, double-click the variable in the list. Variables can be from the following types:

  • Extraction area variable ( [image]),

  • Constant ( [image]),

  • Phonebook request variable ( [image]),

  • Data validation rule variable ( [image]).

To delete a variable in the list, select it and click the [image] button. Note that you can-not remove a variable if it is still referenced in the template.

To add a new variable, click the [image] button. The variable creation wizard is displayed. Follow the instructions to create the new variable.


Displaying the properties of an area variable

Displaying variables properties

Diplaying the properties of an area variable

You can modify or set advanced data extraction rules from the properties of an area variable.

You can use one of the following methods:

  • Select the red rectangle area corresponding to the variable, then:

    • Double-click it,

    • Or right-click it and select Area Properties... from the context menu,

    • Or click [image] in the toolbar.

  • Select Extracted data... from the Document menu. Then double-click the area variable in the list ( [image]).

The Area variable dialog box will be displayed.

Diplaying the properties of a constant

Select Extracted data... from the Document menu. Then double-click the constant in the list ( [image]).

The Constant variable dialog box will be displayed.

Displaying the properties of phonebook request variable

Select Extracted data... from the Document menu. Then double-click the phonebook request variable in the list ( [image]). Also refer to the Phonebook requests section for details.

The LDAP request dialog box or ODBC request dialog box will be displayed.

Displaying the properties of a data validation rule variable

Select Extracted data... from the Document menu. Then double-click the data validation rule variable in the list ( [image]). Also refer to the Data validation rules section for details.

The Data validation rule dialog box will be displayed.


Area: General property sheet

Area - General property sheet

Assigned variable

Enter the name of the variable that will be associated to the area, or select one of the predefined variables from the drop-down list. Click the Advanced... button to set a default value for this variable.

Area

Enter the coordinates of the area associated to the variable, or click the Capture... button to select this area in the reference document, and automatically enter its coordinates.

The coordinates are rectangle coordinates and are given in the following order: row and column of top-left corner, row and column of bottom-right corner (note that to make sense, top value must be lower than bottom value, and left value must be lower than right value).

The value contained in the selected area in the reference document will be displayed in the bottom field.

Skip blanks at the end of each line

Select this check box if you want to ignore blank characters at the end of each line in the area (these blank characters will not be extracted).

Max length

Select this check box if you want to set a maximum length for the retrieved data. This option can be useful when using a regular expression for extraction (see Area: Extractions property sheet).


Area: Extraction property sheet

Area - Extraction property sheet

You can set additional parameters to perform the data extraction.

Recognized expression

Enter in the After field a string that indicates the beginning of the data to extract in the area. By default, this string will not be included in the extracted data. To include it, select the Include this string check box under the After field.

Enter in the Until field a string that indicates the end of the data to extract in the area. By default, this string will not be included in the extracted data. To include it, select the Include this string check box under the Until field.

You can also use regular expressions and choose wildcards characters from the list available by clicking the [image] buttons. See Wildcards for details. Note that if you select one of this characters in the list, the Regular expression option will be automatically checked (see below).

Options

Select the Regular expression check box to use a regular expression for data recognition. Then set your expression in the Expression field. You can choose wildcards characters available from the list by clicking the [image] button. See Wildcards for details.

Select the Case sensitive check box if you want the data recognition to be case sensitive.


Area: Transformations property sheet

Area - Transformations property sheet

Once the data will be extracted, you can apply some transformation to them: remove or add some characters, change case.

Case

Select the case option to apply on the extracted data:

  • Keep case if you want to keep the case used in the document.

  • Lower case if you want all characters to be in lower case.

  • Upper case if you want all characters to be in upper case.

Blanks

You can remove remaining blanks at the beginning or at the end of the extracted data.

  • Select Skip left blanks to remove blanks at the beginning of the extracted data.

  • Select Skip right blanks to remove blanks at the end of the extracted data.

Mask characters

You can choose to remove special characters from the extracted data, or to keep only special characters. To do that:

  • Enter in the Exclude characters all the characters you want to remove from the extracted data.

  • Enter in the Include only characters only the characters you want to keep from the extracted data.

You can use brackets to enter one or more characters, or a range of characters, in which the characters to exclude or include must be found. For example, if you enter [abc] in the Exclude characters field, all "a", "b" and "c" characters will be removed from the extracted data. Or, if you enter [0-9] in the Include only characters field, all non-numeric characters will be removed from the extracted data.


Variable

Default value

Enter the selected variable default value.


Finding references to variables

To find where variables are used in your GDR template, select Find... from the Edit menu.

This will open the Find dialog box.


Find

This dialog box allows you to find where a variable is used in your GDR template. This functionnality is very useful when you want to delete a variable and don't remember where this variable is referenced. Note that you are not allowed to delete a variable that is still referenced somewhere else in the template.

Variable

Select in the list the variable for which you want to find the references in the GDR template.

Use search

Select the type(s) of elements in which you want to find references to the selected variable:

  • Areas ( [image]),

  • Requests conditions ( [image]),

  • Requests output ( [image]),

  • Data validation ( [image]).

Click Find to start the search. The results are displayed in the bottom list.

To display the properties of an item in the result list, double-click it.


Requests - Overview

GDR Designer enables you to set requests to LDAP data sources (Faxgate, Exchange, Lotus Notes, Active directory or another) or ODBC data sources.

Usually, you will set a variable in your template containing an identifier, and use this variable contents to find a data in your phonebook (LDAP or ODBC). The result data value will be assigned to another variable.

For example, you will set a variable for the user name, contained in the document, and use it to retrieve the fax number matching this user name in the phonebook ; you will set another variable to which the result fax number will be assigned.

The variable creation wizard helps you to create LDAP or ODBC requests associated to variables. Refer to Adding variables.


Adding requests to phonebooks

Viewing and adding requests to phonebooks

To display the list of requests defined in your GDR template, select Address Book requests... from the Document menu.

This will open the Requests dialog box, from which you can add new requests.


Requests

This dialog box lists all the requests in LDAP or ODBC phonebooks defined in the GDR template.

List

To add a new request, click the [image] button, and select the phonebook type: LDAP or ODBC.

LDAP phonebook

ODBC phonebook

To change the settings of an existing request, double-click it in the list.

To delete a request in the list, select it and click the [image] button.

To rename an existing request, select it and click the [image] button.


LDAP Request: Request property sheet

LDAP Request - Request property sheet

Search root DN

Enter the DN path of the reference object from which you want to start the search in the Ldap database. Click the [image] to select this path from your database directories.

Scope level

Choose the level of the LDAP request:

  • All sub-levels: returns the reference object and all its descendants.

  • First level only: returns the children of the reference object.

Attributes to extract

Select the attributes that contain the data values you want to retrieve from the LDAP database. The Attribute column list displays the LDAP database attributes.

Select each attribute you want to retrieve data from the list, click in the Variable column and indicate the name of the corresponding variable in the document. You can select a variable from the list (predefined or custom variables), or enter a new variable name.


LDAP Request: Conditions property sheet

LDAP Request - Conditions property sheet

You can enter here one or more condition(s) on the selected object type attributes that must be validated to execute the request in the Ldap database.

  • To add a new condition, click [image]. It will be added at the end of the list.

  • To delete a condition, select it and click [image].

  • To sort the conditions in the list, select them, and use the [image] and [image] buttons. Note that if you move a condition to the beginning of the list, this condition will become an If condition (see below).

Details

The first condition in the list is an If condition. Then, the other conditions can be And or Or conditions. Select the Not check box to use the negative form for these operators (If not, And not, Or not).

To set a condition, you must:

  • Select in the Field list the attribute in the LDAP database on which you want to test the condition.

  • Select an operator for the condition.

  • Select a variable name from the Variable list, whose value will be used in the condition. Or enter a value directly in the Value option field.

The Operator for the condition can be one of the following:

= | The Ldap attribute value must exactly match the Variable value or the Value field contents.
< | The Ldap attribute value must be lower than the Variable value or the Value field contents.
> | The Ldap attribute value must be higher than the Variable value or the Value field contents.
<= | The Ldap attribute value must be lower or equal to the Variable value or the Value field contents.
>= | The Ldap attribute value must be higher or equal to the Variable value or the Value field contents.
~= | The Ldap attribute value must sound like the Variable value or the Value field contents.

If you selected the Variable option, you can set a default value for the selected variable. To do that, click the Advanced... button.

If you selected the Value option, you can use optional characters (*) in the value expression. To include an optional character, click the [image] button and select Optional characters.


ODBC Request: General property sheet

ODBC Request - General property sheet

Data source

Select a data source from the drop-down list. To define a new data source, click the New... button.

Table in the data source

Select the table in your data source containing the information you want to retrieve. The Table list gives all tables in the selected database.

Variables to extract

Select the fields of your data source that contain the data you want to retrieve from the database. The Column column list displays the fields of the selected data source table.

Select each field you want to retrieve data from in the list, click in the Variable column and indicate the name of the corresponding variable in the document. You can select a variable from the list (predefined or custom variable), or enter a new variable name.


Data Source

Name

Enter the name of the datasource containing the data you want to retrieve. Once the datasource is defined, is will be displayed in GDR Designer datasource list.

ODBC Data Source Name

This list displays all the ODBC data source configured on your PC. Select a data source from the list. Note that the chosen data source must be a system data source configured on the fax server (to configure a system data source, open the ODBC Data Sources Administrator in Windows Control Panel and click the System DSN tab).

User name\Password

If necessary, enter the user name and password required to access the data source.


ODBC Request: Conditions property sheet

ODBC Request - Conditions property sheet

You can enter here one or more condition(s) on selected data source table fields that must be validated to execute the request in the data source.

  • To add a new condition, click [image]. It will be added at the end of the list.

  • To delete a condition, select it and click [image].

  • To sort the conditions in the list, select them, and use the [image] and [image] buttons. Note that if you move a condition to the beginning of the list, this condition will become an If condition (see below).

Details

The first condition in the list is an If condition. Then, the other conditions can be And or Or conditions.

To set a condition, you must:

  • Select a field from your data source table in the Field list, on which you want to test the condition.

  • Select an operator for the condition.

  • Select a variable name from the Variable list, whose value will be used in the condition. Or enter a value directly in the Value option field.

The Operator for the condition can be one of the following:

= | The database field value must exactly match the Variable value or the Value field contents.
<> | The database field value must be different from the Variable value or the Value field contents.
< | The database field value must be lower than the Variable value or the Value field contents.
> | The database field value must be higher than the Variable value or the Value field contents.
<= | The database field value must be lower or equal to the Variable value or the Value field contents.
>= | The database field value must be higher or equal to the Variable value or the Value field contents.
like | The database field value must be like the Variable value or the Value field contents.
not like | The database field value must not be like the Variable value or the Value field contents.
is null | The database field value must be null.
is not null | The database field value must not be null.

If you selected the Variable option, you can set a default value for the selected variable. For this, click the Advanced... button.

If you selected the Value option, you can use special characters in the value expression: any character (%) or optional characters (_). To include one of this special characters, click the [image] button. These special characters must be preceded by a \ character to be interpreted as literal: Percent: \%, Underscore: \_ and Back slash: \\.


Setting data validation rules Overview

Data validation rules - Overview

Data validation rules are additional actions to perform according to specific criteria to check. These actions also let you refine the result.

Depending on the method of recovering your information, the rule is to be applied:

  • Either after the extraction of data from specified areas,

  • Or after the execution of queries in an LDAP or ODBC phonebook.

For example, you can add data validation rules in the following cases:

  • To send the document to an administrator, if the value recovered as fax number is nil.

  • To only use the email address if the template allows to get both an email address and a fax number for the recipient, and both an email address and a fax number are found.

  • To assign the value of an extracted variable to another variable.


Adding data validation rules

To display the list of data validation rules defined in your GDR template, select Data validation... from the Document menu.

This will open the Data validation dialog box, from which you can add new requests.


Data validation

This window lets you define additional actions to perform according to specific criteria to check, either after the extraction of data from specified areas, or after the execution of queries in an LDAP or ODBC phonebook. In any case, these actions also let you refine the result.

  • To add an "after area definition" or "after phonebook query", click the [image] button.

  • To rename an "after area definition" or "after phonebook query", click the [image] button.

  • To change the properties of an "after area definition" or "after phonebook query", double-click it.

  • To delete an "after area definition" or "after phonebook query", select it and click the [image] button.

  • Conditions are processed according to the list order. To modify the order of a condition in the list, select it and click [image] or [image].

After areas definitions

This list lets you define the actions that will be performed after the extraction and conversion of data in defined area variables (see Extracted data), provided the associated conditions are validated.

For instance, you can use an "After area definitions" condition to assign a specific value to a variable, if the output of this variable, assigned a fax number, is empty. This specific value could be the administrator's mail address (who would then receive the document that could not be sent and would take appropriate action).

After phonebook queries

This list lets you define the actions that will be performed after queries in phonebooks, provided the associated conditions are validated.

For instance, you can use an additional condition such as "After phonebook query", when a query to an address book returned three fax addresses, and you want to fax the document to a single address only.


Data Validation: Conditions property sheet

Data Validation - Conditions property sheet

Condition list

You can set one or more conditions that will have to be matched in order to exectute the associated action.

There must be at least one condition.

  • To add a new condition, click [image]. It will be added at the end of the list.

  • To delete a condition, select it and click [image].

  • To sort the conditions in the list, select them, and use the [image] and [image] buttons. Note that if you move a condition to the beginning of the list, this condition will become an If condition (see below).

Details

Select the type of the condition. The first condition in the list is an If condition. Then, the other conditions can be And or Or conditions.

Then indicate the variable or area whose contents will be tested in the condition:

  • Select a variable name in the Variable list. This list displays the area variables used in the GDR template.

  • Or, enter in the Area fields the coordinates of an area in the document. You can also click the Capture button to directly select this area in the reference document: the Value and Area fields will be automatically completed. The coordinates in the Area field are rectangle coordinates and are given in the following order: row and column of top-left corner, row and column of bottom-right corner (note that to make sense, top value must be lower than bottom value, and left value must be lower than to right value).

Then, you must select the Operator for the condition, and enter the value that should match the variable or area contents. The following operators are available:

= | The variable or area contents must match exactly the Value field contents.
<> | The variable or area contents must be different from the Value field contents.
< | The variable or area contents must be lower than the Value field contents.
> | The variable or area contents must be higher than the Value field contents.
<= | The variable or area contents must be lower or equal to the Value field contents.
>= | The variable or area contents must be higher or equal to the Value field contents.
contains | The variable or area contents must contain the Value field contents.
not contains | The variable or area contents must not contain the Value field contents.
match | The variable or area contents must match the regular expression entered in the Value field. You can select wildcards from the [image] list to set the regular expression.
not match | The variable or area contents must not match the regular expression entered in the Value field. You can select wildcards from the [image] list to set the regular expression.
starts with | The variable or area contents must start with the Value field contents.
not start with | The variable or area contents must not start with the Value field contents.
ends with | The variable or area contents must end with the Value field contents.
not ends with | The variable or area contents must not end with the Value field contents.

Select the Case sensitive check box if you want the comparison to be case sensitive.


Data Validation: Actions property sheet

Data Validation - Actions property sheet

Action list

You can set one or more actions that will be executed if the associated condition(s) are matched.

  • To add a new action, click [image]. It will be added at the end of the list.

  • To delete an action, select it and click [image].

  • To sort the actions in the list, select them, and use the [image] and [image] buttons.

Action details

Each action consists in changing the value of a specific variable.

Select the name of the variable to change in the Variable list (predefined variable or custom variable). Then indicate the new value for this variable:

  • Its Default value. Refer to Area: General property sheet for more details.

  • A new value to enter in the Value field.

  • Another variable value: select the variable name (predefined variable or custom variable) in the Variable contents list.


GDREdit Menu Bar

GDR Designer Menu bar

File > New

Creates a new GDR template. Not available from Faxgate Administrator.

File > Open

Opens an existing GDR template. Not available from Faxgate Administrator.

File > Save

Saves the current GDR Template.

File > Save As

Saves the current GDR Template with the given file name. Not available from Faxgate Administrator.

File > Close

Closes the current GDR Template. Not available from Faxgate Administrator.

File > Recent file

Displays the list of recent template files opened in GDR Designer. Not available from Faxgate Administrator.

File > Exit

Closes GDR Designer.

Edit > Copy

Copies the selected area variable.

Edit > Paste

Pastes the previously copied area variable.

Edit > Delete

Deletes the selected area variable.

Edit > Find

Looks for variables references. Displays the Find dialog box.

Display > Change font

Changes the display font.

Display > Toolbar

Shows/hides the toolbar.

Display > Status Bar

Shows/hides the status bar.

Document > Settings...

Displays the Document settings dialog box that allows you to set the current document parameters.

Document > Change reference document...

Opens a new reference document for the current GDR template.

Document > Extracted data...

Displays the variables list. Allows you to set new variables.

Document > Address Book requests...

Displays the requests list. Allows you to set new requests to phonebooks.

Document > Data validation...

Displays the data validation rules dialog box.

Document > Test...

Allows you to test your GDR templates.

Tools > Options...

Allows you to set general GDR Designer options.

Help > Contents

Displays help contents.

Help > About GDR Designer

Displays About.


GDREdit Toolbar

GDR Designer Toolbar

Creates a new template. Not available from Faxgate Administrator.

Opens an existing template. Not available from Faxgate Administrator.

Saves the current template.

Creates a new data extraction area.

Displays the selected area properties.

Copies the selected area.

Pastes the previously copied area.

Moves to the previous area.

Moves to the next area.

Displays the variable creation wizard.

Looks for variables references in the current template.

Displays About.


ASCII Control Characters

MEANING | SYMBOL | CHAR | OCT | DEC | HEX
Null | NUL | ^@ | 0 | 0 | 0
Start of Heading | SOH | ^A | 1 | 1 | 1
Start of Text | STX | ^B | 2 | 2 | 2
End of Text | ETX | ^C | 3 | 3 | 3
End of Transmit | EQT | ^D | 4 | 4 | 4
Enquiry | ENQ | ^E | 5 | 5 | 5
Acknowledge | ACK | ^F | 6 | 6 | 6
Bell | BEL | ^G | 7 | 7 | 7
Backspace | BS | ^H | 10 | 8 | 8
Horizontal Tab | HT | ^I | 11 | 9 | 9
Line Feed | LF | ^J | 12 | 10 | A
Vertical Tab | VT | ^K | 13 | 11 | B
Form Feed | FF | ^L | 14 | 12 | C
Carriage Return | CR | ^M | 15 | 13 | D
Shift Out | SO | ^N | 16 | 14 | E
Shift In | SI | ^O | 17 | 15 | F
Data Link Escape | DLE | ^P | 20 | 16 | 10
Device Control 1 | DC1 | ^Q | 21 | 17 | 11
Device Control 2 | DC2 | ^R | 22 | 18 | 12
Device Control 3 | DC3 | ^S | 23 | 19 | 13
Device Control 4 | DC4 | ^T | 24 | 20 | 14
Negative Acknowledge | NAK | ^U | 25 | 21 | 15
Synchronous Idle | SYN | ^V | 26 | 22 | 16
End Transmit Block | ETB | ^W | 27 | 23 | 17
Cancel | CAN | ^X | 30 | 24 | 18
End of Medium | EM | ^Y | 31 | 25 | 19
Substitution | SUB | ^Z | 32 | 26 | 1A
Escape | ESC | ^[ | 33 | 27 | 1B
Figures Shift | FS | ^| | 34 | 28 | 1C
Group Separator | GS | ^] | 35 | 29 | 1D
Record Separator | RS | ^^ | 36 | 30 | 1E
Unit Separator | US | ^ | 37 | 31 | 1F


Options

Tabulations

Enter the text tabulations default size (in number of characters).


Predefined variables

The possible predefined variables values are the following:

Variable name | Description
CoverMessage | Cover page text.
CoverTemplate | Cover page file.
CSID | CSID to send to the remote fax system when transmitting the message.
DeferredShift | Shift used for fax transmission. Enter 1 for shift 1, 2 for shift 2, 3 for shift 3 or anything else for default. In Faxgate Administrator , shifts are set in the Preprocessor properties.
DestIdent | Recipient identifier.
DocumentHandler | Document Handler module identifier.
FaxNumber | Recipient fax number (primary destination). Address type variable.
FaxNumberAlternate | Recipient alternate fax number (alternate destination). Used if the primary destination (FaxNumber) is unavailable. Address type variable.
FormBackground | Template designer parameter. Name of the background bitmap to use for the merge.
FormSignature | Template designer parameter. Signature bitmap to insert in the form.
FormTemplate | Template designer parameter. Name of the template indicating where the text will be inserted on the form.
FromAccount | Sender account (as it will appear on cover page).
FromCompany | Sender company (as it will appear on cover page).
FromCountry | Sender country (as it will appear on cover page).
FromDept | Sender department (as it will appear on cover page).
FromE-mail | Sender E-mail (as it will appear on cover page).
FromFax | Sender fax number (as it will appear on cover page).
FromMail | Sender mail address (as it will appear on cover page).
FromName | Sender name (as it will appear on cover page).
FromPost | Sender zip code (as it will appear on cover page).
FromSub | Sender sub-address (as it will appear on cover page).
FromUser1, FromUser2, FromUser3 | Sender additional description (as it will appear on cover page).
FromVoice | Sender telephone number (as it will appear on cover page).
Header | Header to be used per page/document.
Identifier | Client application ID for the fax. Used by some Faxgate modules to uniquely identify it.
Landscape | Orientation used to send the fax. Enter 0 for portrait (default value) or 1 for landscape.
MaxRetry | Maximum number of retries for a particular fax job.
Notify | Notify mode: E (notify every send attempt), S (notify on successful send), F (notify on final failure), A (notify on successful send or final failure).
NotifyAddress | Notification address in case of fax send failure. The address syntax depends on the NotifyAddressType.
NotifyAddressType | Notification address type in case of fax send failure. The possible values are: LN (Lotus Notes), GW (Groupwise), CC (cc:Mail), MS (MS Mail), SM (SMTP), PR (Printer), FX (Fax machine), AL (16-bit client), AC (LanFax client), LB (Load balanced Fax), AF (ASCII comma delimited file and TIFF file), EX or CN (Exchange), SAP (SAP).
Printer | Printer network path. For example: \\pcprint\myprinter .
PrinterIdent | Printer identifier.
Priority | Message priority. Valid priority codes are: R (Regular ; a blank is equivalent to R), U (Urgent), I (Immediate), L (Low).
RecipientAddress | Recipient address. The address syntax depends on the RecipientType. Address type variable.
RecipientAddressIdent | Recipient address identifier.
RecipientType | Recipient address type. The possible values are: LN (Lotus Notes), GW (Groupwise), CC (cc:Mail), MS (MS Mail), SM (SMTP), PR (Printer), FX (Fax machine), AL (16-bit client), AC (LanFax client), LB (Load balanced Fax), AF (ASCII comma delimited file and TIFF file), EX or CN (Exchange), SAP (SAP).
Subject | Message subject.
ToAccount | Recipient account (as it will appear on cover page).
ToCompany | Recipient company (as it will appear on cover page).
ToCountry | Recipient country (as it will appear on cover page).
ToDept | Recipient department (as it will appear on cover page).
ToE-mail | Recipient E-mail (as it will appear on cover page).
ToMail | Recipient mail address (as it will appear on cover page).
ToName | Recipient name (as it will appear on cover page).
ToPostal | Recipient zip code (as it will appear on cover page).
ToUser1, ToUser2, ToUser3 | Recipient additional description (as it will appear on cover page).
ToVoice | Recipient telephone number.


Wildcards

Wildcards characters

You can use regular expressions for advanced data extraction, when the string to retrieve is not always exactly the same and follows a rule. Regular expressions use special characters named wildcards, which you can combine in expressions.

Here is the list of wildcards you can use in GDR Edit:

Wildcard | Syntax | Description | Sample
Any Char | . | Any character. | 415 675 .... Extracts any string beginning with "415 675 ", followed by exactly 4 characters (any characters).
Character in Range | [-] | Range in which the character extracted must be found. | [0-9] Extracts one numeric character.
Character not in Range | [^-] | Range in which the character extracted must not be found. | f[^0-9]* Extracts any string beginning with "f", followed by 0 to n occurrences of a non-numeric character, i.e, for example: f, fax, fg, for&ldots;
Character List | [] | One or more character in which the character extracted must be found. | [efm] Extracts any string containing the e, f or m characters.
Alternation | | | To extract one of the two characters immediately preceding and following the wildcard. "a|b" indicates that the character extracted will be either "a" or "b". | Email(1|2)? Extracts any string beginning with "Email", followed by 0 or 1 occurrence of "1"or "2", i.e.: Email, Email1, Email2.
Evaluation order | () | To evaluate character sets and define the evaluation order of the expressions.
0 or several times | * | 0 to n occurrences of the character situated immediately to the left. | Fax:.* Extracts any string beginning with "Fax:", followed by 0 to n occurrences of the "any character" character, i.e.: Fax:, Fax: 475.675.7775, Fax: 33.4.72.83.46.40, Fax: 7775, &ldots;.
At least once | + | At least one occurrence of the character situated immediately to the left. | (33)+ Extracts any string containing at least one occurrence of the characters in parenthesis.
Optional | ? | 0 to 1 occurrence of the character situated immediately to the left. | f[0-9]* Extracts any string beginning with "f", followed by 0 to n numeric values, i.e.: f, f0, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, ...

All these wild-cards can be interpreted as literal in an expression if preceded by the character "\":

Left Square Bracket | \[
Right Square Bracket | \]
Left parenthesis | \(
Right parenthesis | \)
Hyphen Minus | \-
Hyphen Plus | \+
Question Mark | \?
Asterisk | \*
Back Slash | \\
Pipe | \|